Dcntl

Section: Dec. 12, 1991 (2)
Updated: MiNT Programmer's Manual
Index Return to Main Contents

NAME

Dcntl - perform a file system specific operation on a file or directory

SYNOPSIS

#include <filesys.h>

LONG Dcntl( WORD cmd, char *name, LONG arg);

DESCRIPTION

Dcntl performs a file system specific command, given by cmd, upon the file or directory specified by name. The exact nature of the operation performed depends upon the file system on which name resides. The interpretation of the third argument arg depends upon the specific command.

The only built-in file system which supports Dcntl operations is the device file system U:\DEV, which understands the following commands:

DEV_INSTALL

Installs a new device driver whose name is given by name (which must be the complete path and file name, e.g. U:\DEV\FOO). The device may be accessed only through GEMDOS file operations; the BIOS will not be aware of it. arg is a pointer to a device descriptor structure:

struct dev_descr {
 /* pointer to device driver structure */
        DEVDRV  *driver;
 /* placed in the "aux" field of file cookies */
        short   dinfo;
 /* either 0 or O_TTY */
        short   flags;
 /* if flags&O_TTY, this points to the tty structure associated
  * with the device
  */
        struct tty *tty;
 /* reserved for future expansion -- set to 0 */
        long    reserved[4];
};

If the attempt to install the device is successful, Dcntl will return a pointer to a structure with type "struct kerinfo" that describes the kernel (see the documentation for loadable file systems for more information on this structure). This structure is in protected memory and can be accessed only in supervisor mode. Moreover, the structure is read only; attempts to write to it will produce unpredictable errors. If there is not enough memory to install the new device, a null pointer will be returned.

DEV_NEWTTY

Installs a driver for a new BIOS terminal device whose name is name (this must be the full path name, e.g. U:\DEV\BAR). arg is the BIOS device number of this device. Note that the BIOS must have been told about the device already via the Bconmap system call or some similar mechanism; otherwise, any attempt to access the file will result in an unknown device error (EUNDEV). This command simply informs the kernel about a BIOS device that already exists, unlike DEV_INSTALL which actually creates a new device.

DEV_NEWBIOS

Installs a driver for a new BIOS non-terminal device whose name is name (this must be the full path name, e.g. U:\DEV\BAR). arg is the BIOS device number of this device. Note that the BIOS must have been told about the device already via the Bconmap system call or some similar mechanism; otherwise, any attempt to access the file will result in an unknown device error (EUNDEV). Like DEV_NEWTTY, this command informs the kernel of the existence of a BIOS device. The difference between the two commands is that DEV_NEWTTY should be used for devices which may be used as terminal devices (e.g. serial lines), whereas DEV_NEWBIOS is useful for devices for which data must be always transmitted "raw" (e.g. a SCSI tape device, or perhaps a LAN device).

RETURNS

The value returned depends on the specific operation requested and the file system involved. Generally, a 0 or positive return value should mean success, and a negative one failure. An exception is the value returned by DEV_INSTALL, which is either a pointer to a kernel information structure, or null on failure.